home *** CD-ROM | disk | FTP | other *** search
/ MacWorld 2003 August / MW 8 2003 CD1.iso / Inside Macworld / Product News / gimp-1.2.4.sit / gimp-1.2.4 / devel-docs / libgimp / sgml / gimpchainbutton.sgml < prev    next >
Encoding:
Text File  |  2003-05-20  |  8.2 KB  |  211 lines
  1. <refentry id="GimpChainButton" revision="19 Jan 2001">
  2. <refmeta>
  3. <refentrytitle>GimpChainButton</refentrytitle>
  4. <manvolnum>3</manvolnum>
  5. <refmiscinfo>LIBGIMP Library</refmiscinfo>
  6. </refmeta>
  7.  
  8. <refnamediv>
  9. <refname>GimpChainButton</refname><refpurpose>Widget to visually connect two entry widgets.</refpurpose>
  10. </refnamediv>
  11.  
  12. <refsynopsisdiv><title>Synopsis</title>
  13. <synopsis>
  14.  
  15.  
  16.  
  17. struct      <link linkend="GimpChainButton-struct">GimpChainButton</link>;
  18. #define     <link linkend="GIMP-CHAIN-BUTTON-CAPS">GIMP_CHAIN_BUTTON</link>               (obj)
  19. enum        <link linkend="GimpChainPosition">GimpChainPosition</link>;
  20. <link linkend="GtkWidget">GtkWidget</link>*  <link linkend="gimp-chain-button-new">gimp_chain_button_new</link>           (<link linkend="GimpChainPosition">GimpChainPosition</link> position);
  21. void        <link linkend="gimp-chain-button-set-active">gimp_chain_button_set_active</link>    (<link linkend="GimpChainButton">GimpChainButton</link> *gcb,
  22.                                              <link linkend="gboolean">gboolean</link> is_active);
  23. <link linkend="gboolean">gboolean</link>    <link linkend="gimp-chain-button-get-active">gimp_chain_button_get_active</link>    (<link linkend="GimpChainButton">GimpChainButton</link> *gcb);
  24.  
  25. </synopsis>
  26. </refsynopsisdiv>
  27.  
  28. <refsect1>
  29. <title>Object Hierarchy</title>
  30. <synopsis>
  31.  
  32.   <link linkend="GtkObject">GtkObject</link>
  33.    +----<link linkend="GtkWidget">GtkWidget</link>
  34.          +----<link linkend="GtkContainer">GtkContainer</link>
  35.                +----<link linkend="GtkTable">GtkTable</link>
  36.                      +----GimpChainButton
  37. </synopsis>
  38.  
  39. </refsect1>
  40.  
  41.  
  42. <refsect1>
  43. <title>Signal Prototypes</title>
  44. <synopsis>
  45.  
  46. "<link linkend="GimpChainButton-toggled">toggled</link>"   void        user_function      (<link linkend="GimpChainButton">GimpChainButton</link> *gimpchainbutton,
  47.                                             <link linkend="gpointer">gpointer</link> user_data);
  48. </synopsis>
  49. </refsect1>
  50.  
  51.  
  52. <refsect1>
  53. <title>Description</title>
  54. <para>
  55. This widget provides a button showing either a linked or a broken
  56. chain that can be used to link two entries, spinbuttons, colors
  57. or other GUI elements and show that they may be locked. Use it for
  58. example to connect X and Y ratios to provide the possibility of a 
  59. constrained aspect ratio.
  60. </para>
  61. <para>
  62. The <link linkend="GimpChainButton">GimpChainButton</link> only gives visual feedback, it does not really 
  63. connect widgets. You have to take care of locking the values yourself 
  64. by checking the state of the <link linkend="GimpChainButton">GimpChainButton</link> whenever a value changes 
  65. in one of the connected widgets and adjusting the other value if 
  66. necessary.
  67. </para>
  68. </refsect1>
  69.  
  70. <refsect1>
  71. <title>Details</title>
  72. <refsect2>
  73. <title><anchor id="GimpChainButton-struct">struct GimpChainButton</title>
  74. <programlisting>struct GimpChainButton;</programlisting>
  75. <para>
  76.  
  77. </para></refsect2>
  78. <refsect2>
  79. <title><anchor id="GIMP-CHAIN-BUTTON-CAPS">GIMP_CHAIN_BUTTON()</title>
  80. <programlisting>#define GIMP_CHAIN_BUTTON(obj)            (GTK_CHECK_CAST ((obj), GIMP_TYPE_CHAIN_BUTTON, GimpChainButton))
  81. </programlisting>
  82. <para>
  83. Checks if the passed pointer is a pointer to a <link linkend="GimpChainButton">GimpChainButton</link> and
  84. performs the cast if valid.
  85. </para><informaltable pgwide=1 frame="none" role="params">
  86. <tgroup cols="2">
  87. <colspec colwidth="2*">
  88. <colspec colwidth="8*">
  89. <tbody>
  90. <row><entry align="right"><parameter>obj</parameter> :</entry>
  91. <entry>The pointer to cast.
  92.  
  93.  
  94. </entry></row>
  95. </tbody></tgroup></informaltable></refsect2>
  96. <refsect2>
  97. <title><anchor id="GimpChainPosition">enum GimpChainPosition</title>
  98. <programlisting>typedef enum
  99. {
  100.   GIMP_CHAIN_TOP,
  101.   GIMP_CHAIN_LEFT,
  102.   GIMP_CHAIN_BOTTOM,
  103.   GIMP_CHAIN_RIGHT
  104. } GimpChainPosition;
  105. </programlisting>
  106. <para>
  107.  
  108. </para></refsect2>
  109. <refsect2>
  110. <title><anchor id="gimp-chain-button-new">gimp_chain_button_new ()</title>
  111. <programlisting><link linkend="GtkWidget">GtkWidget</link>*  gimp_chain_button_new           (<link linkend="GimpChainPosition">GimpChainPosition</link> position);</programlisting>
  112. <para>
  113. Creates a new <link linkend="GimpChainButton">GimpChainButton</link> widget.
  114. </para>
  115. <para>
  116. This returns a button showing either a broken or a linked chain and
  117. small clamps attached to both sides that visually group the two widgets 
  118. you want to connect. This widget looks best when attached
  119. to a table taking up two columns (or rows respectively) next
  120. to the widgets that it is supposed to connect. It may work
  121. for more than two widgets, but the look is optimized for two.</para>
  122. <para>
  123.  
  124. </para><informaltable pgwide=1 frame="none" role="params">
  125. <tgroup cols="2">
  126. <colspec colwidth="2*">
  127. <colspec colwidth="8*">
  128. <tbody>
  129. <row><entry align="right"><parameter>position</parameter> :</entry>
  130. <entry> The position you are going to use for the button
  131. with respect to the widgets you want to chain.
  132. </entry></row>
  133. <row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> Pointer to the new <link linkend="GimpChainButton">GimpChainButton</link>, which is inactive
  134. by default. Use <link linkend="gimp-chain-button-set-active">gimp_chain_button_set_active</link>() to 
  135. change its state.
  136. </entry></row>
  137. </tbody></tgroup></informaltable></refsect2>
  138. <refsect2>
  139. <title><anchor id="gimp-chain-button-set-active">gimp_chain_button_set_active ()</title>
  140. <programlisting>void        gimp_chain_button_set_active    (<link linkend="GimpChainButton">GimpChainButton</link> *gcb,
  141.                                              <link linkend="gboolean">gboolean</link> is_active);</programlisting>
  142. <para>
  143. Sets the state of the <link linkend="GimpChainButton">GimpChainButton</link> to be either locked (TRUE) or 
  144. unlocked (FALSE) and changes the showed pixmap to reflect the new state.</para>
  145. <para>
  146.  
  147. </para><informaltable pgwide=1 frame="none" role="params">
  148. <tgroup cols="2">
  149. <colspec colwidth="2*">
  150. <colspec colwidth="8*">
  151. <tbody>
  152. <row><entry align="right"><parameter>gcb</parameter> :</entry>
  153. <entry> Pointer to a <link linkend="GimpChainButton">GimpChainButton</link>.
  154. </entry></row>
  155. <row><entry align="right"><parameter>is_active</parameter> :</entry>
  156. <entry> The new state.
  157. </entry></row>
  158. </tbody></tgroup></informaltable></refsect2>
  159. <refsect2>
  160. <title><anchor id="gimp-chain-button-get-active">gimp_chain_button_get_active ()</title>
  161. <programlisting><link linkend="gboolean">gboolean</link>    gimp_chain_button_get_active    (<link linkend="GimpChainButton">GimpChainButton</link> *gcb);</programlisting>
  162. <para>
  163. Checks the state of the <link linkend="GimpChainButton">GimpChainButton</link>.</para>
  164. <para>
  165.  
  166. </para><informaltable pgwide=1 frame="none" role="params">
  167. <tgroup cols="2">
  168. <colspec colwidth="2*">
  169. <colspec colwidth="8*">
  170. <tbody>
  171. <row><entry align="right"><parameter>gcb</parameter> :</entry>
  172. <entry> Pointer to a <link linkend="GimpChainButton">GimpChainButton</link>.
  173. </entry></row>
  174. <row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> TRUE if the <link linkend="GimpChainButton">GimpChainButton</link> is active (locked).
  175. </entry></row>
  176. </tbody></tgroup></informaltable></refsect2>
  177.  
  178. </refsect1>
  179.  
  180. <refsect1>
  181. <title>Signals</title>
  182. <refsect2><title><anchor id="GimpChainButton-toggled">The "toggled" signal</title>
  183. <programlisting>void        user_function                  (<link linkend="GimpChainButton">GimpChainButton</link> *gimpchainbutton,
  184.                                             <link linkend="gpointer">gpointer</link> user_data);</programlisting>
  185. <para>
  186.  
  187. </para><informaltable pgwide=1 frame="none" role="params">
  188. <tgroup cols="2">
  189. <colspec colwidth="2*">
  190. <colspec colwidth="8*">
  191. <tbody>
  192. <row><entry align="right"><parameter>gimpchainbutton</parameter> :</entry>
  193. <entry>the object which received the signal.
  194.  
  195. </entry></row>
  196. <row><entry align="right"><parameter>user_data</parameter> :</entry>
  197. <entry>user data set when the signal handler was connected.</entry></row>
  198. </tbody></tgroup></informaltable></refsect2>
  199. </refsect1>
  200.  
  201.  
  202. <refsect1>
  203. <title>See Also</title>
  204. <para>
  205. You may want to use the convenience function <link linkend="gimp-coordinates-new">gimp_coordinates_new</link>() to set 
  206. up two GimpSizeEntries (see <link linkend="GimpSizeEntry">GimpSizeEntry</link>) linked with a <link linkend="GimpChainButton">GimpChainButton</link>.
  207. </para>
  208. </refsect1>
  209.  
  210. </refentry>
  211.